---
title: Next.js (Pages)
description: A guide for installing and using Yamada UI with Next.js pages directory.
---

## Installation

::::steps

### Create application

Create Next.js application.

:::code-group

```bash [pnpm]
pnpm create next-app my-app --typescript
```

```bash [npm]
npx create-next-app my-app --typescript
```

```bash [yarn]
yarn create next-app my-app --typescript
```

```bash [bun]
bun create next-app my-app --typescript
```

:::

### Setup

Running the command will create the necessary files and folders in your project.

:::code-group

```bash [pnpm]
pnpm dlx @yamada-ui/cli init
```

```bash [npm]
npx @yamada-ui/cli init
```

```bash [yarn]
yarn dlx @yamada-ui/cli init
```

```bash [bun]
bunx @yamada-ui/cli init
```

:::

### Install the package

Install `@workspaces/ui` to your application.

:::code-group

```bash [pnpm]
pnpm add "@workspaces/ui@workspace:*"
```

```bash [npm]
npm install "@workspaces/ui@workspace:*"
```

```bash [yarn]
yarn add "@workspaces/ui@workspace:*"
```

```bash [bun]
bun add "@workspaces/ui@workspace:*"
```

:::

### Add provider

After installing, add `UIProvider` to the root of your application.

```tsx title="_app.tsx" {1,6,8}
import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <UIProvider>
      <Component {...pageProps} />
    </UIProvider>
  )
}
```

### Use components

After adding `UIProvider`, you can use the components in your application.

```tsx title="index.tsx" {1,4}
import { Button } from "@workspaces/ui"

export default function Home() {
  return <Button>Click me!</Button>
}
```

That's it! You've successfully set up Yamada UI.

::::

## Scripts

### ColorModeScript

To use [Color Mode](/docs/theming/color-mode), you need to add `ColorModeScript` to the `body` to ensure it works correctly.

This is because color mode is implemented using `localStorage` or `cookies`, and adding the script ensures proper synchronization when the page loads.

::::steps

#### Add Script

```tsx title="_document.tsx" {2,9}
import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript } from "@workspaces/ui"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ColorModeScript type="cookie" />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

If you change the `defaultColorMode` in your [config](/docs/theming/configuration/overview), set the `defaultValue` prop on `ColorModeScript`.

```tsx title="_document.tsx" {3,10}
import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript } from "@workspaces/ui"
import { config } from "@workspace/theme"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ColorModeScript type="cookie" defaultValue={config.defaultColorMode} />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

#### Add getServerSideProps

To share `getServerSideProps` across multiple pages, define `getServerSideSharedProps`.

```tsx title="get-server-side-props.ts"
import { GetServerSidePropsContext } from "next"

export const getServerSideSharedProps = ({
  req,
}: GetServerSidePropsContext) => {
  return {
    props: {
      cookies: req.headers.cookie ?? "",
    },
  }
}
```

```tsx title="index.tsx" {1,4}
import { getServerSideSharedProps } from "@/get-server-side-props"
import { Button } from "@workspaces/ui"

export const getServerSideProps = getServerSideSharedProps

export default function Home() {
  return <Button>Click me!</Button>
}
```

#### Update Provider

```tsx title="_app.tsx" {5,8}
import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  const { cookie } = pageProps

  return (
    <UIProvider cookie={cookie}>
      <Component {...pageProps} />
    </UIProvider>
  )
}
```

::::

### ThemeSchemeScript

To use [theme switching](/docs/theming/switching-themes), you need to add `ThemeSchemeScript` to the `body` to ensure it works correctly.

This is because theme switching is implemented using `localStorage` or `cookies`, and adding the script ensures proper synchronization when the page loads.

::::steps

#### Add Script

```tsx title="_document.tsx" {2,9}
import { Html, Head, Main, NextScript } from "next/document"
import { ThemeSchemeScript } from "@workspaces/ui"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ThemeSchemeScript type="cookie" />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

If you change the `defaultThemeScheme` in your [config](/docs/theming/configuration/overview), set the `defaultValue` prop on `ThemeSchemeScript`.

```tsx title="_document.tsx" {3,12}
import { Html, Head, Main, NextScript } from "next/document"
import { ThemeSchemeScript } from "@workspaces/ui"
import { config } from "@workspace/theme"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ThemeSchemeScript
          type="cookie"
          defaultValue={config.defaultColorMode}
        />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

#### Add getServerSideProps

To share `getServerSideProps` across multiple pages, define `getServerSideSharedProps`.

```tsx title="get-server-side-props.ts"
import { GetServerSidePropsContext } from "next"

export const getServerSideSharedProps = ({
  req,
}: GetServerSidePropsContext) => {
  return {
    props: {
      cookies: req.headers.cookie ?? "",
    },
  }
}
```

```tsx title="index.tsx" {1,4}
import { getServerSideSharedProps } from "@/get-server-side-props"
import { Button } from "@workspaces/ui"

export const getServerSideProps = getServerSideSharedProps

export default function Home() {
  return <Button>Click me!</Button>
}
```

#### Update Provider

```tsx title="_app.tsx" {5,8}
import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  const { cookie } = pageProps

  return (
    <UIProvider cookie={cookie}>
      <Component {...pageProps} />
    </UIProvider>
  )
}
```

::::
